package com.nep.common.service;

import com.nep.entity.supervisor.Report;
import com.nep.entity.supervisor.User;

import java.util.List;

/**
 * UserService 接口定义了用户管理和报告管理相关的服务方法。
 * 该接口提供了用户注册、登录、验证、信息更新以及报告提交和查询等功能。
 */
public interface UserService {

    /**
     * 用户注册方法。
     * 尝试将新用户信息保存到系统中。
     * 在保存之前，会检查手机号是否已被注册。
     *
     * @param user 要注册的用户对象，包含手机号、密码、真实姓名、年龄、性别和网格地址等信息。
     * @return 如果注册成功返回 true，若手机号已存在或保存过程中出现异常则返回 false。
     */
    boolean register(User user);

    /**
     * 用户登录方法。
     * 根据用户输入的手机号和密码进行验证。
     *
     * @param phone    用户的手机号码，作为唯一标识。
     * @param password 用户输入的登录密码。
     * @return 如果手机号和密码匹配，返回对应的用户对象；若不匹配或未找到该用户，返回 null。
     */
    User login(String phone, String password);

    /**
     * 验证用户方法。
     * 检查输入的手机号和密码是否与系统中已注册的用户信息匹配。
     *
     * @param phone    用户的手机号码。
     * @param password 用户输入的密码。
     * @return 如果手机号和密码匹配，返回 true；否则返回 false。
     */
    boolean validateUser(String phone, String password);

    /**
     * 通过手机号获取用户信息的方法。
     * 根据提供的手机号在系统中查找对应的用户。
     *
     * @param phone 用户的手机号码。
     * @return 如果找到匹配的用户，返回该用户对象；若未找到，返回 null。
     */
    User getUserByPhone(String phone);

    /**
     * 更新用户信息的方法。
     * 根据传入的用户对象更新系统中该用户的信息。
     *
     * @param user 包含要更新信息的用户对象，使用手机号作为唯一标识。
     * @return 如果更新成功返回 true，若未找到该用户或更新过程中出现异常则返回 false。
     */
    boolean updateUser(User user);

    /**
     * 提交报告的方法。
     * 用户可以通过该方法提交环境相关的报告。
     * 系统会为报告自动生成唯一的报告 ID 和创建时间。
     *
     * @param report 要提交的报告对象，包含用户 ID、用户名、AQI 等级、描述、网格地址等信息。
     * @return 如果报告提交成功返回 true，若保存过程中出现异常则返回 false。
     */
    boolean submitReport(Report report);

    /**
     * 根据用户 ID 获取报告列表的方法。
     * 该方法用于查询指定用户提交的所有报告。
     *
     * @param userId 用户的唯一标识（手机号码）。
     * @return 返回一个包含该用户所有报告的列表，如果没有找到相关报告，返回一个空列表。
     */
    List<Report> getReportsByUserId(String userId);
}